Crate rune

Visit the site 🌐 - Read the book 📖

An embeddable dynamic programming language for Rust.

Contributing

If you want to help out, there should be a number of optimization tasks available in Future Optimizations. Or have a look at Open Issues.

Create an issue about the optimization you want to work on and communicate that you are working on it.

Highlights of Rune

• Clean Rust integration 💻.
• Memory safe through reference counting 📖.
• Template literals 📖.
• Try operators 📖.
• Pattern matching 📖.
• Structs and enums 📖 with associated data and functions.
• Dynamic vectors 📖, objects 📖, and tuples 📖 with built-in serde support 💻.
• First-class async support 📖.
• Generators 📖.
• Dynamic instance functions 📖.
• Stack isolation 📖 between function calls.
• Stack-based C FFI, like Lua’s (TBD).

Rune scripts

You can run Rune programs with the bundled CLI:

cargo run --bin rune -- run scripts/hello_world.rn

If you want to see detailed diagnostics of your program while it’s running, you can use:

cargo run --bin rune -- run scripts/hello_world.rn --dump-unit --trace --dump-vm

See --help for more information.

Running scripts from Rust

You can find more examples in the examples folder.

The following is a complete example, including rich diagnostics using termcolor. It can be made much simpler if this is not needed.

use rune::termcolor::{ColorChoice, StandardStream};
use rune::EmitDiagnostics as _;
use runestick::{Vm, FromValue as _, Item, Source};

use std::error::Error;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let context = runestick::Context::with_default_modules()?;
    let options = rune::Options::default();

    let mut sources = rune::Sources::new();
    sources.insert(Source::new(
        "script",
        r#"
        pub fn calculate(a, b) {
            println("Hello World");
            a + b
        }
        "#,
    ));

    let mut diagnostics = rune::Diagnostics::new();

    let result = rune::load_sources(&context, &options, &mut sources, &mut diagnostics);

    if !diagnostics.is_empty() {
        let mut writer = StandardStream::stderr(ColorChoice::Always);
        diagnostics.emit_diagnostics(&mut writer, &sources)?;
    }

    let unit = result?;
    let vm = Vm::new(Arc::new(context.runtime()), Arc::new(unit));

    let mut execution = vm.execute(&["calculate"], (10i64, 20i64))?;
    let value = execution.async_complete().await?;

    let value = i64::from_value(value)?;

    println!("{}", value);
    Ok(())
}

Re-exports

pub use self::emit_diagnostics::termcolor;

Modules

ast

AST for the Rune language.

macros

The macro system of Rune.

Macros

K

Helper macro to reference a specific token kind, or short sequence of kinds.

T

Helper macro to reference a specific token.

quote

Macro helper function for quoting the token stream as macro output.

Structs

CompileError

An error raised during compiling.

Diagnostics

Structure to collect compilation diagnostics.

Error

An error raised when using one of the load_* functions.

FileSourceLoader

A filesystem-based source loader.

Id

An opaque identifier that is associated with AST items.

ImportEntryStep

A single stap as an import entry.

IrError

An error raised during compiling.

Lexer

Lexer for the rune language.

LoadSourcesError

Error raised when we failed to load sources.

MacroContext

Context for a running macro.

NoopCompileVisitor

A compile visitor that does nothing.

Options

Compiler options.

ParseError

An error raised during parsing.

Parser

Parser for the rune language.

Peeker

Construct used to peek a parser.

QueryError

An error raised during querying.

Quote

ToTokens implementation generated by quote_fn.

ResolveError

An error during resolving.

ScopeError

An error cause by issues with scoping.

Sources

A collection of source files, and a queue of things to compile.

Storage

Storage for synthetic language items.

TokenStream

A token stream.

TokenStreamIter

A token stream iterator.

UnitBuilder

Instructions from a single source file.

Warning

Compilation warning.

Enums

BuildError

CompileErrorKind

Compiler error.

ConfigurationError

Error when parsing configuration.

Diagnostic

A single diagnostic.

DiagnosticsError

Errors that can be raised when formatting diagnostics.

ErrorKind

IrErrorKind

Error when encoding AST.

IrValue

A constant value.

LinkerError

An error raised during linking.

ParseErrorKind

Error when parsing.

QueryErrorKind

Error raised during queries.

ResolveErrorKind

The kind of a resolve error.

ScopeErrorKind

Used

Indication whether a value is being evaluated because it’s being used or not.

WarningKind

Compilation warning kind.

Traits

CompileVisitor

A visitor that will be called for every language item compiled.

DumpInstructions

Trait to dump the instructions of a unit to the given writer.

EmitDiagnostics

Helper trait for emitting diagnostics.

EmitSource

Helper trait to emit source code locations.

OptionSpanned

Types for which we can optionally get a span.

Parse

The parse trait, implemented by items that can be parsed.

Peek

Implemented by tokens that can be peeked for.

Resolve

A type that can be resolved to an internal value based on a source.

ResolveOwned

Trait for resolving a token into an owned value.

SourceLoader

A source loader.

Spanned

Types for which we can get a span.

ToTokens

Trait for things that can be turned into tokens.

Functions

compile

Compile the given source with default options.

load_sources

Load and compile the given sources.

load_sources_with_visitor

Load the specified sources with a visitor.

parse_all

Parse the given input as the given type that implements Parse.

with_context

Install the given context and call the provided function with the installed context.

Type Definitions

CompileResult

A compile result.